Release 10.1A: OpenEdge Development:
Programming Interfaces

SAX-attributes object

When the parser encounters an XML Start-Tag that has one or more attributes, such as:

<Entry name=”John Smith” id=”2543”>

it populates the Start Element callback’s attributes parameter with information on the element’s attributes (in the example, “name” and “id”). In Progress, the attributes parameter is a handle to a Progress SAX-attributes object, which is similar to the Attributes interface of the Java Sax2 API.

The attributes and methods associated with the SAX-attributes object are summarized in Table 20–3. For reference entries, see the OpenEdge Development: Progress 4GL Reference .

Table 20–3: SAX-attributes attribute and method summary 

This attribute or method...	Lets you...
NUM-ITEMS attribute	Get how many attributes the XML element has.
GET-INDEX-BY-NAMESPACE-NAME() method GET-INDEX-BY-QNAME() method	Get where on the attribute list a particular attribute resides.
GET-LOCALNAME-BY-INDEX() method GET-QNAME-BY-INDEX() method GET-URI-BY-INDEX() method	Get the name of a particular attribute.
GET-TYPE-BY-INDEX() method GET-TYPE-BY-NAMESPACE-NAME() method GET-TYPE-BY-QNAME( ) method	Get the type of a particular attribute.
GET-VALUE-BY-INDEX() method GET-VALUE-BY-NAMESPACE-NAME() method GET-VALUE-BY-QNAME() method	Get the value of a particular attribute.
TYPE attribute	Get the type of the object (which is always “SAX-ATTRIBUTE”).
ADM-DATA attribute PRIVATE-DATA attribute UNIQUE-ID attribute	Get or set information concerning this particular SAX-attributes object.

A SAX-attributes object is a collection of all the attributes for a given element. No matter how many attributes an element has, StartElement gets passed only one attributes handle. Think of it as a list of the attributes associated with the element.

Note: The order of the elements on the list might not be the same as the order in which they appear in the document — which is consistent with the SAX2 Java API specification.

To get the information about each attribute from a SAX-attributes object, use the GET-XXX methods. They let your application to get the SAX-attributes data in either of two different ways:

You can traverse the list, getting each attribute’s data in turn by using the GET-XXX-BY-INDEX methods.
You can use an attribute’s name to get its data.

This approach has variations, depending on whether you are using namespace processing or not. For more information on this point, see the "Namespace Processing" section.)

There are 6 pieces of information you can get on each attribute, though three are variations on the name. Each GET-XXX method gets you one piece of information. The six pieces of information and the GET-XXX methods are explained in Table 20–4.

Table 20–4: The GET-XXX methods 

To get this information on an attribute...	Use these methods...
Its position on the list	GET-INDEX-BY-NAMESPACE-NAME() GET-INDEX-BY-QNAME()
Its Namespace URI, if namespace information is available	GET-URI-BY-INDEX()
Its localName, if namespace processing is being enabled	GET-LOCALNAME-BY-INDEX()
Its Qualified name (qName)	GET-QNAME-BY-INDEX()
Its XML attribute type (declared in the DTD or XML schema)	GET-TYPE-BY-INDEX() GET-TYPE-BY-NAMESPACE-NAME() GET-TYPE-BY-QNAME()
Its value	GET-VALUE-BY-INDEX() GET-VALUE-BY-NAMESPACE-NAME() GET-VALUE-BY-QNAME()

If the parser is doing Namespace processing — that is, if SAX-reader’s SUPPRESS-NAMESPACE-PROCESSING attribute is set to “NO” (the default) — each attribute that has a namespace prefix will have non-empty URI, localName, and qName data. An attribute that has noNamespace prefix will have an empty URI, but its localName and qName will have values.

Note: An unprefixed attribute name does not use the default Namespace, if any; it is not associated with any Namespace. This contrasts with the case for Elements, where unprefixed Element names use the default Namespace, if any.

If the parser is not doing Namespace processing, each attribute will have only a qName.

In all cases, the qName will be exactly what appears in the XML document.